Initial specification of JDQL #520

gavinking · 2024-03-05T12:22:23Z

Pushing this to collect feedback/suggestions in a disciplined way. Plenty of things still to clarify, of course.

spec/src/main/asciidoc/query-language.asciidoc

spec/src/antlr/JDQL.g4

njr-11

This looks great - it amounts to a very useful subset of JPQL which at least at first glances looks like it will cover everything you can do with Query by Method Name, plus some additional capability beyond that, which is good because it gives advanced users the ability to do some more powerful things with queries. I didn't review in depth yet, especially with regard to double checking that everything is a subset of JPQL (and I hope we can rely on Jakarta Persistence spec community for that as well). I included a few initial comments, but this is definitely headed in the right direction and it's exciting how far along it already is!

spec/src/antlr/JDQL.g4

spec/src/main/asciidoc/query-language.asciidoc

spec/src/antlr/JDQL.g4

spec/src/main/asciidoc/query-language.asciidoc

spec/src/main/asciidoc/repository.asciidoc

spec/src/main/asciidoc/query-language.asciidoc

gavinking · 2024-03-08T23:33:43Z

Looks like I need to rebase this.

Co-authored-by: Nathan Rauh <[email protected]>

- sorting - counting, or - functions.

gavinking · 2024-03-12T10:28:28Z

I just reviewed the existing comments, and made a couple of very minor changes. I believe that all existing feedback has now been addressed.

(it's already defined by the grammar)

njr-11

This looks good. I didn't find much new because a lot of it we have reviewed already. I added a few minor comments/typo fixes. Feel free to ignore the suggestions that aim to avoid hard coding the Jakarta Persistence specification version number and section numbers if you don't like that idea.

spec/src/main/asciidoc/query-language.asciidoc

njr-11 · 2024-03-12T20:47:41Z

spec/src/main/asciidoc/query-language.asciidoc

+
+In the JDQL grammar, identifiers are labelled with the `IDENTIFIER` token type.
+
+The following identifiers are _keywords_: `select`, `update`, `set`, `delete`, `from`, `where`, `order`, `by`, `asc`, `desc`, `not`, `and`, `or`, `between`, `like`, `in`, `null`, `local`, `true`, `false`. In addition, every reserved identifier listed in section 4.4.1 of the Jakarta Persistence specification version 3.2 is also considered a reserved identifier. Keywords and other reserved identifiers are case-insensitive: `null`, `Null`, and `NULL` are three ways to write the same keyword.


The following would make it so that we don't need to update the reference to Jakarta Persistence specification version number with each new release. The tradeoff is that it is not as explicit.

Suggested change

The following identifiers are _keywords_: `select`, `update`, `set`, `delete`, `from`, `where`, `order`, `by`, `asc`, `desc`, `not`, `and`, `or`, `between`, `like`, `in`, `null`, `local`, `true`, `false`. In addition, every reserved identifier listed in section 4.4.1 of the Jakarta Persistence specification version 3.2 is also considered a reserved identifier. Keywords and other reserved identifiers are case-insensitive: `null`, `Null`, and `NULL` are three ways to write the same keyword.

The following identifiers are _keywords_: `select`, `update`, `set`, `delete`, `from`, `where`, `order`, `by`, `asc`, `desc`, `not`, `and`, `or`, `between`, `like`, `in`, `null`, `local`, `true`, `false`. In addition, every reserved identifier listed in the "Identifiers" section of the Jakarta Persistence specification is also considered a reserved identifier. Keywords and other reserved identifiers are case-insensitive: `null`, `Null`, and `NULL` are three ways to write the same keyword.

Mmmmm. Hrrrrm. The assumption here is that section numbers are much more likely to change than section titles, which is probably true ... but I dunno, a single-word doesn't seem like a wonderful sort of reference. Not sure if this is a good idea or not.

Right, the section title could also change and we would be similarly broken. Neither of the options are ideal. I wasn't sure if the suggested change would be an improvement and decided to identify the possibility of it. If it isn't an improvement, we can leave the references to the numbers and mark this conversation resolved.

spec/src/main/asciidoc/query-language.asciidoc

njr-11 · 2024-03-12T21:02:35Z

spec/src/main/asciidoc/query-language.asciidoc

+
+If the JDQL implementation does not support a one of the standard functions explicitly listed above, it must throw `UnsupportedOperationException` when the function name occurs in a query. Alternatively, the Jakarta Data provider is permitted to reject a repository method declaration at compilation time if its `@Query` annotation uses an unsupported function.
+
+NOTE: On the other hand, an implementation of JDQL might provide additional built-in functions, and might even allow invocation of user-defined functions. Section 4.7 of the Jakarta Persistence specification defines a set of functions that all JPQL implementations are required to provide, including `concat`, `substring`, `trim`, `locate`, `ceiling`, `floor`, `exp`, `ln`, `mod`, `power`, `round`, `sign`, `sqrt`, `cast`, `extract`, `coalesce`, and `nullif`. JDQL implementations are encouraged to support any of these functions which are reasonably implementable.


The following could be done to remain correct if the sections are renumbered in Jakarta Persistence.

Suggested change

NOTE: On the other hand, an implementation of JDQL might provide additional built-in functions, and might even allow invocation of user-defined functions. Section 4.7 of the Jakarta Persistence specification defines a set of functions that all JPQL implementations are required to provide, including `concat`, `substring`, `trim`, `locate`, `ceiling`, `floor`, `exp`, `ln`, `mod`, `power`, `round`, `sign`, `sqrt`, `cast`, `extract`, `coalesce`, and `nullif`. JDQL implementations are encouraged to support any of these functions which are reasonably implementable.

NOTE: On the other hand, an implementation of JDQL might provide additional built-in functions, and might even allow invocation of user-defined functions. The section of the Jakarta Persistence specification titled "Scalar Expressions" defines a set of functions that all JPQL implementations are required to provide, including `concat`, `substring`, `trim`, `locate`, `ceiling`, `floor`, `exp`, `ln`, `mod`, `power`, `round`, `sign`, `sqrt`, `cast`, `extract`, `coalesce`, and `nullif`. JDQL implementations are encouraged to support any of these functions which are reasonably implementable.

njr-11 · 2024-03-12T21:08:18Z

spec/src/main/asciidoc/query-language.asciidoc

+
+==== Numeric types and numeric type promotion
+
+The type assigned to an operator expression depends on the types of its operand expression, which need not be identical. The rules for numeric promotion are given in section 4.7 of the Jakarta Persistence specification version 3.2:


Suggested change

The type assigned to an operator expression depends on the types of its operand expression, which need not be identical. The rules for numeric promotion are given in section 4.7 of the Jakarta Persistence specification version 3.2:

The type assigned to an operator expression depends on the types of its operand expression, which need not be identical. The rules for numeric promotion are given in the "Scalar Expressions" section of the Jakarta Persistence specification:

spec/src/main/asciidoc/query-language.asciidoc

spec/src/antlr/JDQL.g4

Co-authored-by: Nathan Rauh <[email protected]>

spec/src/antlr/JDQL.g4

for compatibility with latest revision of JPA 3.2

njr-11

I'm approving the pull, but we should consider if Contains was still useful for String attributes. The other option here would be to remove only the part that says it applies to collections.
Also, I didn't see where the removed keywords are added to the reserved list (in case there is a need to bring them back in the future), so we will need to be sure to cover that separately.

gavinking · 2024-03-16T14:47:59Z

I'm approving the pull, but we should consider if Contains was still useful for String attributes. The other option here would be to remove only the part that says it applies to collections.

I wondered that, but then figured that since it's just a variation of Like that it wasn't really that useful. But I can put it back if necessary.

Also, I didn't see where the removed keywords are added to the reserved list (in case there is a need to bring them back in the future), so we will need to be sure to cover that separately.

You mean Contains and Empty? You want to add a new list of "Keywords Reserved for Future Use"?

gavinking · 2024-03-16T14:50:00Z

To be specific: findByNameContains("hello%world") is the same as findByNameLike("%hello%world%").

njr-11 · 2024-03-16T15:22:30Z

To be specific: findByNameContains("hello%world") is the same as findByNameLike("%hello%world%").

It is, but it requires the repository user to supply the % on their parameter, which might not be very natural to their usage, and they might not even like to know about wildcard characters. In your particular example, that user wouldn't care because they were already using a % in the middle of their pattern. But if they only wanted a single word or part of a word, they might not want to bother with wildcard characters on the ends of it.

njr-11 · 2024-03-16T15:25:44Z

You mean Contains and Empty? You want to add a new list of "Keywords Reserved for Future Use"?

I don't think we need a new section. There is one in module-info here that can be used:

 * <h3>Reserved for Future Use</h3>

The important part of this is notifying the user to avoid them so that we would have the freedom to add them back if the need arises.

gavinking · 2024-03-16T15:30:15Z

It is, but it requires the repository user to supply the % on their parameter, which might not be very natural to their usage, and they might not even like to know about wildcard characters.

So if you want it back just say the word....

gavinking · 2024-03-16T15:31:21Z

You mean Contains and Empty? You want to add a new list of "Keywords Reserved for Future Use"?

I don't think we need a new section. There is one in module-info here that can be used:
 * <h3>Reserved for Future Use</h3>

Ugh. It gives me the heezy-jeebys when something is only mentioned in that module-info.java.

gavinking · 2024-03-16T15:43:04Z

Well, see 7805071.

- bring Contains back to life (but only from Strings) - add Empty to reserved words

otaviojava · 2024-03-17T05:55:10Z

@gavinking could you fix the conflict?

gavinking · 2024-03-17T07:18:42Z

@gavinking could you fix the conflict?

Done.

gavinking changed the title ~~Draft specification of JDQL~~ Proposed draft specification of JDQL Mar 5, 2024

gavinking requested review from njr-11, otaviojava and graemerocher March 5, 2024 12:24

otaviojava reviewed Mar 5, 2024

View reviewed changes

spec/src/main/asciidoc/query-language.asciidoc Show resolved Hide resolved

otaviojava reviewed Mar 5, 2024

View reviewed changes

spec/src/main/asciidoc/query-language.asciidoc Show resolved Hide resolved

otaviojava reviewed Mar 5, 2024

View reviewed changes

spec/src/antlr/JDQL.g4 Show resolved Hide resolved

njr-11 reviewed Mar 5, 2024

View reviewed changes

graemerocher reviewed Mar 6, 2024

View reviewed changes

spec/src/main/asciidoc/query-language.asciidoc Outdated Show resolved Hide resolved

graemerocher reviewed Mar 6, 2024

View reviewed changes

spec/src/antlr/JDQL.g4 Show resolved Hide resolved

graemerocher reviewed Mar 6, 2024

View reviewed changes

spec/src/antlr/JDQL.g4 Show resolved Hide resolved

graemerocher reviewed Mar 6, 2024

View reviewed changes

spec/src/main/asciidoc/query-language.asciidoc Outdated Show resolved Hide resolved

graemerocher reviewed Mar 6, 2024

View reviewed changes

spec/src/main/asciidoc/query-language.asciidoc Outdated Show resolved Hide resolved

graemerocher reviewed Mar 6, 2024

View reviewed changes

spec/src/main/asciidoc/repository.asciidoc Show resolved Hide resolved

otaviojava reviewed Mar 7, 2024

View reviewed changes

spec/src/main/asciidoc/query-language.asciidoc Outdated Show resolved Hide resolved

njr-11 reviewed Mar 8, 2024

View reviewed changes

spec/src/main/asciidoc/query-language.asciidoc Show resolved Hide resolved

gavinking and others added 12 commits March 9, 2024 00:36

Draft specification of JDQL

abf00cd

add note about requirements surrounding JDQL functions

c8ff958

Update spec/src/main/asciidoc/query-language.asciidoc

b831e30

Co-authored-by: Nathan Rauh <[email protected]>

clarify semantics of path expression involving null elements

b95049c

Update spec/src/main/asciidoc/query-language.asciidoc

d807f9c

Co-authored-by: Nathan Rauh <[email protected]>

Update spec/src/main/asciidoc/query-language.asciidoc

451b0c3

Co-authored-by: Nathan Rauh <[email protected]>

further clarify requirements for path expressions

7f80fd4

clarify what happens if the database doesn't support:

925b8e1

- sorting - counting, or - functions.

simplify select clause to a single path expression

14a867e

add LOCAL TIME

613a267

define enum order

659ef96

undefine enum order

352b511

gavinking force-pushed the jdql branch from a3df286 to 352b511 Compare March 8, 2024 23:37

gavinking force-pushed the jdql branch 2 times, most recently from a355847 to 547de83 Compare March 12, 2024 11:04

gavinking changed the title ~~Proposed draft specification of JDQL~~ Initial specification of JDQL Mar 12, 2024

gavinking force-pushed the jdql branch from 547de83 to 247d5e7 Compare March 12, 2024 11:06

add discussion of operator precedence to text

d13676c

(it's already defined by the grammar)

gavinking force-pushed the jdql branch from 247d5e7 to d13676c Compare March 12, 2024 11:12

njr-11 reviewed Mar 12, 2024

View reviewed changes

Apply suggestions from code review

ebbda9d

Co-authored-by: Nathan Rauh <[email protected]>

njr-11 reviewed Mar 15, 2024

View reviewed changes

spec/src/antlr/JDQL.g4 Outdated Show resolved Hide resolved

gavinking added 2 commits March 15, 2024 23:51

'count(*)' -> 'count(this)'

b761d12

for compatibility with latest revision of JPA 3.2

remove Contains and Empty operators from QbMN

43c8875

njr-11 approved these changes Mar 16, 2024

View reviewed changes

gavinking force-pushed the jdql branch 2 times, most recently from 1856752 to 48bea10 Compare March 16, 2024 15:42

for @njr-11

7805071

- bring Contains back to life (but only from Strings) - add Empty to reserved words

gavinking force-pushed the jdql branch from 48bea10 to 7805071 Compare March 16, 2024 15:45

njr-11 approved these changes Mar 16, 2024

View reviewed changes

Merge branch 'main' into jdql

be1e8d6

otaviojava merged commit 21104da into jakartaee:main Mar 17, 2024
3 checks passed

gavinking mentioned this pull request Mar 17, 2024

Update the Javadoc of @Query after merge of JDQL #551

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Initial specification of JDQL #520

Initial specification of JDQL #520

gavinking commented Mar 5, 2024 •

edited

Loading

njr-11 left a comment

gavinking commented Mar 8, 2024

gavinking commented Mar 12, 2024

njr-11 left a comment

njr-11 Mar 12, 2024

gavinking Mar 12, 2024

njr-11 Mar 13, 2024

njr-11 Mar 12, 2024

njr-11 Mar 12, 2024

njr-11 left a comment

gavinking commented Mar 16, 2024

gavinking commented Mar 16, 2024

njr-11 commented Mar 16, 2024

njr-11 commented Mar 16, 2024

gavinking commented Mar 16, 2024

gavinking commented Mar 16, 2024

gavinking commented Mar 16, 2024 •

edited

Loading

otaviojava commented Mar 17, 2024

gavinking commented Mar 17, 2024


		In the JDQL grammar, identifiers are labelled with the `IDENTIFIER` token type.

		The following identifiers are _keywords_: `select`, `update`, `set`, `delete`, `from`, `where`, `order`, `by`, `asc`, `desc`, `not`, `and`, `or`, `between`, `like`, `in`, `null`, `local`, `true`, `false`. In addition, every reserved identifier listed in section 4.4.1 of the Jakarta Persistence specification version 3.2 is also considered a reserved identifier. Keywords and other reserved identifiers are case-insensitive: `null`, `Null`, and `NULL` are three ways to write the same keyword.


		If the JDQL implementation does not support a one of the standard functions explicitly listed above, it must throw `UnsupportedOperationException` when the function name occurs in a query. Alternatively, the Jakarta Data provider is permitted to reject a repository method declaration at compilation time if its `@Query` annotation uses an unsupported function.

		NOTE: On the other hand, an implementation of JDQL might provide additional built-in functions, and might even allow invocation of user-defined functions. Section 4.7 of the Jakarta Persistence specification defines a set of functions that all JPQL implementations are required to provide, including `concat`, `substring`, `trim`, `locate`, `ceiling`, `floor`, `exp`, `ln`, `mod`, `power`, `round`, `sign`, `sqrt`, `cast`, `extract`, `coalesce`, and `nullif`. JDQL implementations are encouraged to support any of these functions which are reasonably implementable.


		==== Numeric types and numeric type promotion

		The type assigned to an operator expression depends on the types of its operand expression, which need not be identical. The rules for numeric promotion are given in section 4.7 of the Jakarta Persistence specification version 3.2:

Initial specification of JDQL #520

Initial specification of JDQL #520

Conversation

gavinking commented Mar 5, 2024 • edited Loading

njr-11 left a comment

Choose a reason for hiding this comment

gavinking commented Mar 8, 2024

gavinking commented Mar 12, 2024

njr-11 left a comment

Choose a reason for hiding this comment

njr-11 Mar 12, 2024

Choose a reason for hiding this comment

gavinking Mar 12, 2024

Choose a reason for hiding this comment

njr-11 Mar 13, 2024

Choose a reason for hiding this comment

njr-11 Mar 12, 2024

Choose a reason for hiding this comment

njr-11 Mar 12, 2024

Choose a reason for hiding this comment

njr-11 left a comment

Choose a reason for hiding this comment

gavinking commented Mar 16, 2024

gavinking commented Mar 16, 2024

njr-11 commented Mar 16, 2024

njr-11 commented Mar 16, 2024

gavinking commented Mar 16, 2024

gavinking commented Mar 16, 2024

gavinking commented Mar 16, 2024 • edited Loading

otaviojava commented Mar 17, 2024

gavinking commented Mar 17, 2024

gavinking commented Mar 5, 2024 •

edited

Loading

gavinking commented Mar 16, 2024 •

edited

Loading